home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / t3_1 / xlib.lha / xlib / cdecl / document < prev    next >
Text File  |  1990-05-29  |  5KB  |  167 lines
  1. An Introduction to the Scheme->C C Declaration Compiler
  2. -------------------------------------------------------
  3.  
  4. The C declaration compiler is a tool for generating stub procedures to access
  5. C structures and library functions.  It was designed to allow Scheme->C to
  6. access the X11 Xlib.  This document is intended to be an introduction to the
  7. language.  For complete understanding of its use,  the reader should examine
  8. the Xlib declaration files and the declaration compiler.
  9.  
  10. The declaration compiler is invoked by:
  11.  
  12.      cdecl  class  command  cdecl-files...
  13.  
  14. where "class" is the name of the set of declarations and "command" is
  15. one of the following:
  16.  
  17.      -const            Emits constant definitions to the files
  18.                 classCONSTANTS.sc and classCONSTANTS.sch.
  19.  
  20.     -extern            Emits external procedures for each cdecl-file
  21.                 containing extern definitions to files named
  22.                 <cdecl-file-root>.sc and <cdecl-file-root>.sch.
  23.  
  24.     -typedef        Emits type definitions for structures to the
  25.                 files <type-name>.sc and <type-name>.sch.
  26.                 Emits all type checking functions and type
  27.                 definitions for objects other than structs or
  28.                 unions to classTYPES.sc and classTYPES.sch.
  29.  
  30. The command is then followed by one or more files containing declarations.
  31. The declaration files normally have the file extension ".cdecl".
  32.  
  33. Declaration Language
  34. --------------------
  35.  
  36. The declaration files contain constant, type, and external procedure
  37. definitions.  A constant is defined by expressions of the form:
  38.  
  39.     (const <identifier> <expression>)
  40.  
  41. where the expression is evaluated at compile time and is defined as the
  42. following:
  43.  
  44.     <expression> ::= <constant-symbol>
  45.                  Scheme-constant
  46.                  ( Scheme-procedure [ <expression> ... ] )
  47.  
  48. Types are defined by expressions of the following form:
  49.  
  50.     (typedef <type> <identifier>)
  51.  
  52. where:
  53.  
  54.     <type> ::= (<stype> *)
  55.            (<stype> *proc)
  56.  
  57.     <atype> ::= (<stype> integer)
  58.             <struct-or-union-specifier>
  59.  
  60.     <stype> ::= char
  61.             shortint
  62.             shortunsigned
  63.             int
  64.             unsigned
  65.             float
  66.             double
  67.             <type-def-name>
  68.  
  69.     <type-def-name> ::= <identifier> denoting another type
  70.  
  71.     <struct-or-union-specifier> ::=    ( struct [<struct-decl> ...] )
  72.                     ( union  [<struct-decl> ...] )
  73.  
  74.     <struct-decl> ::= ( <atype> <identifier> )
  75.  
  76. The final form of expression is used to define external procedures:
  77.  
  78.     ( EXTERN <type> <fname> [ <arg> ... ] )
  79.  
  80. where:
  81.  
  82.     <fname>  ::= a Scheme string
  83.  
  84.     <arg>     ::= ( <type> <id> )
  85.              ( IN <type> <id> )
  86.              ( OUT <type> <id> )
  87.              ( IN_OUT <type> <id> )
  88.  
  89.     <id>     ::= a Scheme symbol
  90.  
  91. Since the declaration source file is a file of Scheme expressions, it is case
  92. insensative and it may contain Scheme comments.
  93.  
  94. An Example
  95. ----------
  96.  
  97. The use of the declaration language is best shown by example.  A few C
  98. declarations from X11's Xlib are:
  99.  
  100.     #define DoRed   (1<<0)
  101.     #define DoGreen (1<<1)
  102.     #define DoBlue  (1<<2)
  103.  
  104.     typedef struct {
  105.         unsigned long pixel;
  106.         unsigned short red, green, blue;
  107.         char flags;
  108.         char pad;
  109.     } XColor;
  110.  
  111.     typedef struct _XDisplay{
  112.         .
  113.         .
  114.         .
  115.     } Display;
  116.  
  117.     typedef int Status;
  118.     typedef unsignedlong XID;
  119.     typedef XID Colormap;
  120.     
  121.     extern Status XLookupColor();
  122.  
  123. Converted to the declaration language, they become:
  124.  
  125.     (const dored 1)
  126.     (const dogreen 2)
  127.     (const doblue 4)
  128.  
  129.     (typedef (struct
  130.             (unsigned pixel)
  131.             (shortunsigned red)
  132.             (shortunsigned green)
  133.             (shortunsigned blue)
  134.             (char flags)
  135.             (char pad)
  136.     ) xcolor)
  137.     (typedef (xcolor *) xcolorp)
  138.     (typedef (xcolor 0) xcolora)
  139.     (typedef (xcolora *) xcolorap)
  140.  
  141.     (typedef (struct) display)
  142.     (typedef (display *) displayp)
  143.  
  144.     (typedef int status)
  145.     (typedef unsigned xid)
  146.     (typedef xid colormap)
  147.  
  148.     (extern status "XLookupColor"
  149.         (displayp dpy)
  150.         (colormap cmap)
  151.         (string spec)
  152.         (out xcolor def) (out xcolor scr))
  153.  
  154. The constants are converted in a straight-forward manner, only noting that case
  155. does not count in Scheme.  When the struct XColor is converted, declaration
  156. lists must be broken up into multiple statements.  In addition, types are
  157. added to define a pointer to an XColor struct, xcolorp, an array of
  158. indeterminate size of the XColor structs, xcolora, and a pointer to such an
  159. array, xcolorap.  The struct, Display, is defined an an "opaque" type, display,
  160. with a pointer to one defined as displayp.  Unlike C, procedure interfaces have
  161. the type of each argument specified.  Since Scheme has automatic storage
  162. management, functions may return new instances of structured objects.  This is
  163. noted in the declarations, where def and scr are noted as "out" arguments.
  164.  
  165. The reader should now consult the Scheme->C Xlib documentation for the Scheme
  166. programmer's view of the resulting interface.
  167.